Ta strona została przetłumaczona przez Cloud Translation API.

Cykl życia transakcji płatniczej

Dowiedz się, jak sprzedawcy integrują aplikacje płatnicze i jak działają transakcje płatnicze za pomocą interfejsu Payment Request API.

Eiji Kitamura

Milica Mihajlija

Interfejsy API płatności internetowych to dedykowane funkcje płatności wbudowane po raz pierwszy w przeglądarce. Dzięki płatnościom internetowym integracja sprzedawcy z aplikacjami do płatności staje się łatwiejsza, a wrażenia klientów stają się bardziej płynne i bezpieczniejsze.

Aby dowiedzieć się więcej o korzyściach płynących z użycia płatności internetowych, przeczytaj artykuł Wzmocnienie aplikacji do płatności za pomocą płatności internetowych.

Z tego artykułu dowiesz się, jak wygląda transakcja płatności w witrynie sprzedawcy, oraz jak działa integracja aplikacji do płatności.

Proces składa się z 6 etapów:

Sprzedawca inicjuje transakcję płatniczą.
Sprzedawca wyświetla przycisk płatności.
Klient naciska przycisk płatności.
Przeglądarka uruchamia aplikację do płatności.
Jeśli klient zmieni jakiekolwiek szczegóły (np. opcje dostawy lub adres), sprzedawca zaktualizuje szczegóły transakcji, aby odzwierciedlić tę zmianę.
Gdy klient potwierdzi zakup, sprzedawca zweryfikuje płatność i dokończy transakcję.

Krok 1. Sprzedawca inicjuje transakcję płatniczą

Gdy klient zdecyduje się na zakup, sprzedawca inicjuje transakcję płatniczą, tworząc obiekt PaymentRequest. Ten obiekt zawiera ważne informacje o transakcji:

akceptowane formy płatności i dane potrzebne do przetworzenia transakcji;
szczegóły, takie jak łączna cena (wymagane) i informacje o produktach;
Opcje, w których sprzedawcy mogą poprosić o informacje o dostawie, takie jak adres dostawy i opcja dostawy.
Sprzedawcy mogą też poprosić o adres rozliczeniowy, imię i nazwisko płatnika, adres e-mail oraz numer telefonu.
Sprzedawcy mogą też podać opcjonalny typ dostawy (shipping, delivery lub pickup) w polu PaymentRequest. Aplikacja do płatności może użyć tego jako wskazówki, aby wyświetlić odpowiednie etykiety w interfejsie.

const request = new PaymentRequest([{
  supportedMethods: 'https://bobpay.xyz/pay',
  data: {
    transactionId: '****'
  }
}], {
  displayItems: [{
    label: 'Anvil L/S Crew Neck - Grey M x1',
    amount: { currency: 'USD', value: '22.15' }
  }],
  total: {
    label: 'Total due',
    amount: { currency: 'USD', value : '22.15' }
  }
}, {
  requestShipping: true,
  requestBillingAddress: true,
  requestPayerEmail: true,
  requestPayerPhone: true,
  requestPayerName: true,
  shippingType: 'delivery'
});

Dodawanie identyfikatora transakcji

Niektórzy dostawcy usług płatniczych mogą wymagać od sprzedawcy podania identyfikatora transakcji, który został wcześniej wydany jako część informacji o transakcji. Typowa integracja obejmuje komunikację między serwerem sprzedawcy a serwerem obsługującym płatności w celu zarezerwowania łącznej ceny. Zapobiega to manipulowaniu cenami i oszustwom ze strony nieuczciwych klientów, ponieważ weryfikacja na końcu transakcji jest przeprowadzana przez sprzedawcę.

Sprzedawca może przekazać identyfikator transakcji jako część właściwości data obiektu PaymentMethodData.

Po otrzymaniu informacji o transakcji przeglądarka przechodzi przez proces wykrywania aplikacji do płatności określonych w PaymentRequest na podstawie identyfikatorów metod płatności. Dzięki temu przeglądarka może określić aplikację do płatności, którą należy uruchomić, gdy tylko sprzedawca będzie gotowy do przeprowadzenia transakcji.

Szczegółowe informacje o procesie wykrywania znajdziesz w artykule Konfigurowanie metody płatności.

Krok 2. Sprzedawca wyświetla przycisk płatności

Sprzedawcy mogą obsługiwać wiele form płatności, ale powinni wyświetlać przyciski płatności tylko dla tych, których klient może faktycznie używać. Wyświetlanie przycisku płatności, który nie działa, to niewygoda dla użytkowników. Jeśli sprzedawca może przewidzieć, że metoda płatności określona w obiekcie PaymentRequest nie będzie odpowiednia dla klienta, może podać alternatywne rozwiązanie lub w ogóle nie wyświetlać tego przycisku.

Korzystając z PaymentRequest, sprzedawca może sprawdzić, czy klient ma dostępną aplikację do płatności.

Czy klient ma aplikację do płatności?

Metoda PaymentRequest z parametrem canMakePayment() zwraca wartość true, jeśli na urządzeniu klienta jest dostępna aplikacja do płatności. „Dostępna” oznacza, że aplikacja obsługująca formę płatności została wykryta i zainstalowana (w przypadku aplikacji na daną platformę) lub że aplikacja internetowa obsługująca formę płatności jest gotowa do zarejestrowania.

const canMakePayment = await request.canMakePayment();
if (!canMakePayment) {
  // Fallback to other means of payment or hide the button.
}

Krok 3. Klient naciska przycisk płatności

Gdy klient naciśnie przycisk płatności, sprzedawca wywoła metodę show() instancji PaymentRequest, która natychmiast uruchamia interfejs płatności.

Jeśli ostateczna łączna cena jest ustawiana dynamicznie (np. pobierana z serwera), sprzedawca może opóźnić uruchomienie interfejsu płatności do czasu, gdy będzie znana łączna kwota.

Odłożenie uruchomienia interfejsu płatności

Obejrzyj demonstrację odrywania płatności w interfejsie użytkownika do czasu ustalenia ostatecznej łącznej ceny.

Aby odłożyć wyświetlenie interfejsu płatności, sprzedawca przekazuje obietnicę do metody show(). Do momentu spełnienia obietnicy i rozpoczęcia transakcji przeglądarka będzie wyświetlać wskaźnik wczytywania.

const getTotalAmount = async () => {
  // Fetch the total amount from the server, etc.
};

try {
  const result = await request.show(getTotalAmount());
  // Process the result…
} catch(e) {
  handleError(e);
}

Jeśli jako argument funkcji show() nie zostanie podany żaden obietni, przeglądarka natychmiast uruchomi interfejs płatności.

Krok 4. Przeglądarka uruchamia aplikację do płatności

Przeglądarka może uruchomić aplikację do płatności na platformie lub w przeglądarce (więcej informacji znajdziesz w artykule Jak Chrome określa, którą aplikację do płatności uruchomić).

Sposób tworzenia aplikacji do płatności zależy w dużej mierze od dewelopera, ale zdarzenia emitowane przez sprzedawcę i do niego oraz struktura danych przekazywanych wraz z tymi zdarzeniami są standaryzowane.

Gdy aplikacja do płatności zostanie uruchomiona, otrzyma informacje o transakcji przekazane do obiektu PaymentRequest w kroku 1. Informacje te obejmują:

Dane formy płatności
Łączna cena
Opcje płatności

Aplikacja do płatności używa informacji o transakcji do etykietowania interfejsu użytkownika.

Krok 5. Jak sprzedawca może zaktualizować szczegóły transakcji w zależności od działań klienta

Klienci mogą zmienić szczegóły transakcji, takie jak forma płatności i opcja dostawy, w aplikacji do płatności. Podczas wprowadzania zmian sprzedawca otrzymuje zdarzenia zmiany i aktualizuje szczegóły transakcji.

Sprzedawca może otrzymywać 4 rodzaje zdarzeń:

Zdarzenie zmiany formy płatności
Zdarzenie zmiany adresu dostawy
Zdarzenie zmiany opcji dostawy
Zdarzenie weryfikacji sprzedawcy

Zdarzenie zmiany formy płatności

Aplikacja do płatności może obsługiwać wiele form płatności, a sprzedawca może oferować zniżkę zależnie od wyboru klienta. Aby obsłużyć ten przypadek użycia, zdarzenie zmiany formy płatności może poinformować sprzedawcę o nowej formie płatności, aby mógł zaktualizować łączną cenę ze zniżką i zwrócić ją do aplikacji płatniczej.

request.addEventListener('paymentmethodchange', e => {
  e.updateWith({
    // Add discount etc.
  });
});

Zdarzenie zmiany adresu dostawy

Aplikacja do płatności może opcjonalnie podać adres dostawy klienta. Jest to wygodne dla klientów, ponieważ nie muszą ręcznie wpisywać żadnych szczegółów w formularzu. Mogą też zapisać adres dostawy w preferowanych aplikacjach do płatności, zamiast w wielu różnych witrynach sprzedawców.

Jeśli po zainicjowaniu transakcji klient zaktualizuje adres dostawy w aplikacji do płatności, sprzedawca otrzyma zdarzenie 'shippingaddresschange'. To zdarzenie pomaga sprzedawcy określić koszt dostawy na podstawie nowego adresu, zaktualizować łączną cenę i zwrócić ją do aplikacji płatniczej.

request.addEventListener('shippingaddresschange', e => {
  e.updateWith({
    // Update the details
  });
});

Jeśli sprzedawca nie może wysłać przesyłki na zaktualizowany adres, może przesłać komunikat o błędzie, dodając parametr błędu do szczegółów transakcji zwracanych do aplikacji płatniczej.

Zdarzenie zmiany opcji dostawy

Sprzedawca może zaoferować klientowi kilka opcji dostawy i może przekazać wybór aplikacji do płatności. Opcje dostawy są wyświetlane jako lista cen i nazw usług, spośród których klient może wybierać. Na przykład:

Dostawa standardowa – bezpłatna
Dostawa ekspresowa – 5 USD

Gdy klient zaktualizuje opcję dostawy w aplikacji do płatności, sprzedawca otrzyma zdarzenie 'shippingoptionchange'. Sprzedawca może następnie określić koszt dostawy, zaktualizować łączną cenę i zwrócić ją do aplikacji płatniczej.

request.addEventListener('shippingoptionchange', e => {
  e.updateWith({
    // Update the details
  });
});

Sprzedawca może też dynamicznie modyfikować opcje dostawy na podstawie adresu dostawy klienta. Jest to przydatne, gdy sprzedawca chce zaoferować różne opcje dostawy klientom krajowym i zagranicznym.

Zdarzenie weryfikacji sprzedawcy

Aby zapewnić dodatkowe bezpieczeństwo, aplikacja do płatności może przeprowadzić weryfikację sprzedawcy przed przejściem do procesu płatności. Projekt mechanizmu weryfikacji zależy od aplikacji do płatności, ale zdarzenie weryfikacji sprzedawcy służy do informowania sprzedawcy o adresie URL, którego może użyć do weryfikacji.

request.addEventListener('merchantvalidation', e => {
  e.updateWith({
    // Use `e.validateURL` to validate
  });
});

Krok 6. Sprzedawca weryfikuje płatność i kończy transakcję

Gdy klient autoryzuje płatność, metoda show() zwraca obietnicę, która jest rozwiązywana do PaymentResponse. Obiekt PaymentResponse zawiera te informacje:

Szczegóły wyniku płatności
Adres dostawy
Opcja dostawy
Informacje kontaktowe

W tym momencie w interfejsie przeglądarki może być nadal widoczny wskaźnik wczytywania, co oznacza, że transakcja nie została jeszcze ukończona.

Jeśli aplikacja do płatności zostanie zakończona z powodu błędu lub nieudanej płatności, obietnica z show() zostanie odrzucona, a przeglądarka zakończy transakcję płatności.

Przetwarzanie i weryfikowanie płatności

Wartość details w elementach PaymentResponse to obiekt danych uwierzytelniających płatności zwrócony z aplikacji do dokonywania płatności. Sprzedawca może użyć tych danych, aby przetworzyć lub zweryfikować płatność. Sposób działania tego kluczowego procesu zależy od podmiotu obsługującego płatności.

Dokonywanie lub ponowne próbowanie transakcji

Gdy sprzedawca ustali, czy transakcja została zrealizowana, czy nie, może:

Aby zrealizować transakcję i zamknąć wskaźnik wczytywania, wywołaj metodę .complete().
Poproś klienta o ponowne wywołanie metody retry().

async function doPaymentRequest() {
  try {
    const request = new PaymentRequest(methodData, details, options);
    const response = await request.show();
    await validateResponse(response);
  } catch (err) {
    // AbortError, SecurityError
    console.error(err);
  }
}

async function validateResponse(response) {
  try {
    const errors = await checkAllValuesAreGood(response);
    if (errors.length) {
      await response.retry(errors);
      return validateResponse(response);
    }
    await response.complete("success");
  } catch (err) {
    // Something went wrong…
    await response.complete("fail");
  }
}
// Must be called as a result of a click
// or some explicit user action.
doPaymentRequest();

Następne kroki

Więcej informacji o deklarowaniu identyfikatora formy płatności znajdziesz w artykule Konfigurowanie formy płatności.
Więcej informacji o tworzeniu aplikacji płatniczej dla konkretnej platformy znajdziesz w przewodniku dla deweloperów aplikacji płatniczych na Androida.
Więcej informacji o tworzeniu aplikacji do płatności internetowych znajdziesz w przewodniku dla deweloperów.